---
title: MockServer
layout: default
---

<div class="header">
	<h1>MockServer</h1>

	<h2 itemprop="headline">Easy mocking of any system you integrate with via HTTP or HTTPS</h2>
</div>

<a href="https://github.com/jamesdbloom/mockserver"><img style="position: absolute; top: 0; right: 0; border: 0;" width="149" height="149" src="images/forkme_right_red.png" alt="Fork us on GitHub"></a>


<a name="what-is-mockserver" class="anchor" href="#what-is-mockserver">&nbsp;</a>

<div class="build_tag">
	<a href="https://buildkite.com/mockserver/mockserver"><img src="https://badge.buildkite.com/3b6803f4fe98cb5ed7bf18292a1434f800b53d8fecb92811d8.svg?style=square&theme=slack&branch=master" alt="BuildKite Build Status"></a>
	<a href="https://gitter.im/jamesdbloom/mockserver?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Gitter" style="padding-bottom: 1px;"></a>
</div>

<h2>What is MockServer</h2>

<p>MockServer can be used for mocking any system you integrate with via HTTP or HTTPS (i.e. services, web sites, etc).</p>

<p>When MockServer receives a requests it matches the request against active <strong>expectations</strong> that have been configured.</p>

<p>An <strong>expectation</strong> defines the <strong>action</strong> that is taken, for example, a response could be returned.</p>

<p>MockServer supports the follow <strong>actions</strong>:</p>
<ul>
	<li>
        <strong>return a "mock" <a href="/mock_server/creating_expectations.html#mock_response">response</a></strong> when a request matches an <a href="/mock_server/creating_expectations.html">expectation</a>
        <p><a href="images/expectation_response_action.png" target="_blank"><img class="action_image" src="images/expectation_response_action.png" alt="Response Action Expectation"></a></p>
    </li>
	<li>
        <strong><a href="/mock_server/creating_expectations.html#mock_forward">forward</a> a request</strong> when the request matches an <a href="/mock_server/creating_expectations.html">expectation</a> (i.e. a dynamic port forwarding proxy)
        <p><a href="images/expectation_forward_action.png" target="_blank"><img class="action_image" src="images/expectation_forward_action.png" alt="Forward Action Expectation"></a></p>
    </li>
	<li>
        <strong>execute a <a href="/mock_server/creating_expectations.html#callback">callback</a></strong> when a request matches an <a href="/mock_server/creating_expectations.html">expectation</a>, allowing the response to be created dynamically
        <p><a href="images/expectation_callback_action.png" target="_blank"><img class="action_image" src="images/expectation_callback_action.png" alt="Callback Action Expectation"></a></p>
    </li>

    <li>
        <strong>return an <a href="/mock_server/creating_expectations.html#mock_error">invalid response</a></strong> or close the connection when a request matches an <a href="/mock_server/creating_expectations.html">expectation</a>
        <p><a href="images/expectation_error_action.png" target="_blank"><img class="action_image" src="images/expectation_error_action.png" alt="Error Action Expectation"></a></p>
    </li>
	<li>
        <strong><a href="/mock_server/verification.html">verify</a> requests</strong> have been sent (i.e. as a test assertion)
        <p><a href="images/verification.png" target="_blank"><img class="action_image" src="images/verification.png" alt="Verification"></a></p>
    </li>
    <li>
        <strong><a href="/mock_server/verification.html">retrieve</a> logs</strong>, <strong>requests</strong> or <strong>expectations</strong> to help debug
        <p><a href="images/retrieve_logs.png" target="_blank"><img class="action_image" src="images/retrieve_logs.png" alt="Retrieve Logs"></a></p>
    </li>
</ul>

<h2>What is MockServer Proxy</h2>

<p>MockServer Proxy can be used for transparently recording all requests sent by a system (i.e. an application or set of applications).</p>

<p>MockServer Proxy can:</p>
<ul>
	<li><strong><a href="/proxy/getting_started.html">proxy</a> all requests</strong> using any of the following proxying methods:
		<ul class="sublist">
			<li>Port Forwarding</li>
			<li>Web Proxying (i.e. HTTP proxy)</li>
			<li>HTTPS Tunneling Proxying (using HTTP CONNECT)</li>
			<li>SOCKS Proxying (i.e. dynamic port forwarding)</li>
		</ul>
	</li>
	<li><strong><a href="/proxy/verification.html">verify</a> requests</strong> have been sent (i.e. in a test assertion)</li>
	<li><strong><a href="/proxy/getting_started.html">record</a> requests and responses</strong> to analyse how a system behaves</li>
</ul>

<p>The MockServer Proxy provides the following features:</p>

<ul>
	<li><strong>Port Forwarding</strong>
		<ul>
			<li>all requests for a specific local port are forwarded to a different (local or remote) port and hostname for the system being proxied</li>
			<li>to proxy requests the <strong>HTTP client</strong> should <a href="/proxy/configuring_sut.html">use the hostname and port of the MockServer Proxy</a> instead of the system being proxied</li>
		</ul>
	</li>
	<li><strong>Web Proxying</strong> (i.e. HTTP proxy)
		<ul>
			<li>each request is forwarded dynamically using its Host header</li>
			<li>to proxy requests the <strong>HTTP client</strong> should <a href="/proxy/configuring_sut.html">be configured to use an HTTP Proxy</a></li>
		</ul>
	</li>
	<li><strong>Secure Web Proxying</strong> (i.e. HTTPS tunneling proxying)
		<ul>
			<li>requests are forwarded using a CONNECT request that setups an HTTP tunnel</li>
			<li>an SSL certificate is auto-generated allowing encrypted HTTPS traffic to be recorded transparently</li>
			<li>to proxy requests the <strong>HTTP client</strong> should <a href="/proxy/configuring_sut.html">be configured to use an HTTP Proxy</a></li>
		</ul>
	</li>
	<li><strong>SOCKS Proxying</strong> (i.e. dynamic port forwarding)
		<ul>
			<li>requests are forwarded using a SOCK CONNECT CMD request that established a socket tunnel</li>
			<li>if the traffic is encrypted an SSL certificate is auto-generated allowing SSL traffic to be recorded transparently</li>
			<li>to proxy requests the <strong>operating system (or JVM)</strong> should <a href="/proxy/configuring_sut.html">be configured to use an HTTP Proxy</a></li>
		</ul>
	</li>
	<li><strong>SSL & Certificates</strong>
		<ul>
			<li>all SSL traffic is handled transparently by auto-generating an appropriate SSL certificate</li>
			<li>generated certificates use a single <a href="https://github.com/jamesdbloom/mockserver/blob/master/mockserver-core/src/main/resources/org/mockserver/socket/CertificateAuthorityCertificate.pem">MockServer root CA certificate</a> enabling the root certificate to be
				<a href="/proxy/configuring_sut.html">easily imported</a></li>
		</ul>
	</li>
	<li><strong>Port Unification</strong>
		<ul>
			<li>to simplify configuration all protocols (i.e. HTTP, HTTPS / SSL, SOCKS, etc) are supported on the same port</li>
			<li>the protocol is dynamically detected by both MockServer and MockServer Proxy</li>
		</ul>
	</li>
</ul>

<a name="why-use-mockserver" class="anchor" href="#why-use-mockserver">&nbsp;</a>

<h2>Why use MockServer</h2>

<p>MockServer allows you to mock any server or service that you connect to over HTTP or HTTPS, such as a REST or RPC service. </p>

<p>This is useful in the following scenarios:</p>

<ul>
	<li>testing
		<ul>
			<li>easily recreate all types of responses for HTTP dependencies such as REST or RPC services to test applications easily and affectively</li>
			<li>isolate the system-under-test to ensure tests run reliably and only fail when there is a genuine bug. It is important only the system-under-test is tested and not its dependencies to avoid tests failing due to irrelevant external changes such as network failure or a server being rebooted / redeployed.</li>
			<li>easily setup mock responses independently for each test to ensure test data is encapsulated with each test. Avoid sharing data between tests that is difficult to manage and maintain and risks tests infecting each other</li>
			<li>create test assertions that verify the requests the system-under-test has sent</li>
		</ul>
	</li>
	<li>de-coupling development
		<ul>
			<li>start working against a service API before the service is available. If an API or service is not yet fully developed MockServer can mock the API allowing any team who is using the service to start work without being delayed</li>
			<li>isolate development teams during the initial development phases when the APIs / services may be extremely unstable and volatile. Using MockServer allows development work to continue even when an external service fails</li>
		</ul>
	</li>
	<li>isolate single service
		<ul>
			<li>during deployment and debugging it is helpful to run a single application or service or handle a sub-set of requests on on a local machine in debug mode. Using MockServer it is easy to <a href="/mock_server/isolating_single_service.html">selectively forward requests to a local process</a> running in debug mode, all other request can be forwarded to the real services for example running in a QA or UAT environment</li>
		</ul>
	</li>
</ul>

<p><strong>Mocking Dependencies & Verifying Request</strong></p>

<p>A system with service dependencies, as follows:</p>

<p><a href="images/system_in_production.png" target="_blank"><img src="images/system_in_production.png" alt="System In Production" style="max-width:100%;"></a></p>

<p>MockServer could be used to mock the service dependencies, as follows:</p>

<p><a href="images/system_under_test_with_mockserver.png" target="_blank"><img itemprop="image" src="images/system_under_test_with_mockserver.png" alt="Mocking service dependencies with MockServer" style="max-width:100%;"></a></p>

<p><strong>Isolating Single Service / Application</strong></p>

<p>A single page application may load static resources such as HTML, CSS and JavaScript from a web server and also make AJAX calls to one or more separate services, as follows:</p>

<p><a href="images/single_page_application.png" target="_blank"><img src="images/single_page_application.png" alt="Single Page Application" style="max-width:100%;"></a></p>

<p>To isolate a single AJAX service, for development or debugging, the MockServer can selectively forward specific requests to local instance of the service:</p>

<p><a href="images/isolate_single_service_with_mockserver.png" target="_blank"><img src="images/isolate_single_service_with_mockserver.png" alt="Isolating Single Service" style="max-width:100%;"></a></p>

<p>Using MockServer as a content routing load balancer is described in more detail in the section called <a href="/mock_server/isolating_single_service.html">Isolate Single Service</a>.</p>

<h2>Why use MockServer Proxy</h2>

<p>MockServer proxy allows you to record request from the system-under-test or two analysis an existing system by recording outbound requests.</p>

<p>This is useful in the following scenarios:</p>

<ul>
	<li>testing
		<ul>
			<li>create test assertions that verify the requests the system-under-test has been sent, without needing to mock any requests</li>
		</ul>
	</li>
	<li>analyse existing system
		<ul>
			<li>record all outbound requests so it is possible to analise and under stand what outbound requests an existing system is making</li>
		</ul>
	</li>
	<li>debug HTTP interactions
		<ul>
			<li>log all outbound requests so it is possible to visualise all interactions (for example from a browser) to external services. This is particularly important as network analysis tools in browsers such as Chrome do not accurately show all network interactions, such as, favicon.ico requests.  In addition many proxies do not handle encrypted HTTPS traffic, however, MockServer Proxy auto-generates certificates using a single <a href="https://github.com/jamesdbloom/mockserver/blob/master/mockserver-core/src/main/resources/org/mockserver/socket/CertificateAuthorityCertificate.pem">MockServer root CA certificate</a> enabling the root certificate to be <a href="/proxy/configuring_sut.html">easily imported</a></li>
		</ul>
	</li>
	<li>record & replay
		<ul>
			<li>all recorded requests can be converted into Java code or JSON expectations to simplify the creation of mocks for complex test scenarios</li>
		</ul>
	</li>
</ul>

<p><strong>Recording Requests & Analysing Behaviour</strong></p>

<p>MockServer Proxy can record all outbound requests, as follows:</p>

<p><a href="images/recording_requests_with_mockserver_proxy.png" target="_blank"><img src="images/recording_requests_with_mockserver_proxy.png" alt="Recording service requests with MockServer Proxy" style="max-width:100%;"></a></p>

<p><strong>Verifying Request</strong></p>

<p>MockServer Proxy can verify service requests, as follows:</p>

<p><a href="images/system_under_test_with_mockserver_proxy.png" target="_blank"><img src="images/system_under_test_with_mockserver_proxy.png" alt="Verifying service requests with MockServer Proxy" style="max-width:100%;"></a></p>
